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PREFACE’ 


The  purpose  of  the  EOITSPEC  system  reports  is  to  provide  com¬ 
plete  documentation  to  all  personnel  involved  with  the  EDITSPEC 
system.  Such  personnel  include  managers,  specification  writers,  typ 
ists,  computer  systems  analysts,  and  computer  programmers.  Each  per¬ 
sonnel  group  requires  different  documentation.  The  reports  required 
for  each  group  and  the  order  in  which  they  should  be  read  are  shown 
in  the  table  below. 


Accession  For 
NTT '  ORAAI 
DT’.J  TA* 

Unannounced  □ 

justification - 


By - - - 

Distribution/ 


ABSTRACT 


This  report  provides  computer  programmers  with  procedures  for 
changing,  extending,  and  converting  the  EDITSPEC  system.  Procedures 
to  be  used  in  contracting  for  computer  services  are  detailed.  Pro¬ 
gram  and  data  conversion  procedures  are  described  as  are  testing  pro¬ 
cedures  to  insure  that  the  conversion  has  been  performed  correctly. 
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FOREWORD 


This  investigation  was  performed  for  the  Directorate  of  Military 
Construction,  Office  of  the  Chief  of  Engineers  (OCE),  under  Project 
4A762731AT41,  "Design,  Construction,  and  Operation  and  Maintenance 
Technology  for  Military  Facilities";  Task  Tl,  "Development  of  Auto¬ 
mated  Procedures  for  Military  Construction";  Work  Unit  009,  "Com¬ 
puter-Based  Specifications."  The  applicable  QCR  is  1.10.001.  The 
OCE  Technical  Monitor  was  William  Darnell. 

The  study  was  performed  by  the  Management  Systems  Branch  (Dr.  0. 
E.  Rood,  dr.,  Chief),  Facility  Acquisition  and  Construction  Division 
(Mr.  E.  A.  Lotz,  Chief),  U.S.  Army  Construction  Engineering  Research 
Laboratory  (CERL). 

COL  Louis  J.  Circeo  is  Commander  and  Director  of  CERL  and  Dr.  L. 
R.  Shaffer  is  Technical  Director. 


r 


CONTENTS 


L 


£2Si 

PREFACE  ^ 

REPORTS  REQUIRED  AND  REVIEW  ORDER  \ 

ABSTRACT  J 

FOREWORD  * 

1  PROGRAM  DOCUMENTATION  TAPES  6 

2  CHANGES  TO  THE  EDITSPEC  SYSTEM  PROGRAMS  7 

3  CONTRACTING  FOR  COMPUTER  SERVICES  9 

Starting  the  Process 
Activities  to  be  Performed 


Previous  Contracts 

4  PROGRAM  CONVERSION  11 

5  OVERLAY  STRUCTURE  12 

6  SYSTEM  INTEGRATION  TEST  13 

7  BENCHMARK  PROCEDURES  14 

Introduction 


Initial  System  Loading 
Test  One 
Test  Two 

Comparison  of  Tests  One  and  Two 
Test  Three 

Benchmark  Test  Performance 


8  DATA  CONVERSION 


16 


EOITSPEC  SYSTEMS  MANUAL 

VOLUME  V:  CONVERSION  AND  EXTENSION 


1  PROGRAM  DOCUMENTATION  TAPES 


To  provide  a  complete  record  of  all  computer  programs  ever 
written  for  the  EDITSPEC  system,  a  series  of  documentation  tapes  has 
been  preserved.  All  tapes  are  unlabeled,  written  at  a  density  of  800' 
bpi,  and  blocked  with  800  characters  per  block.  Each  record  is  80 
characters  long. 

The  programs  are  listed  in  alphabetical  order  by  functional 
area,  one  program  per  file.  The  FORTRAN  version  of  each  program  is 
given  first,  followed  by  the  assembly  language  program  written  to  re¬ 
place  the  FORTRAN  program.  Assembly  language  and  rewritten  FORTRAN 
programs  are  given  in  chronological  order.  The  computer-system  and 
operating-system  version  are  recorded  in  each  assembly  program  in  the 
first  few  comment  cards. 

All  assembly  programs  have  been  saved  so  that  EDITSPEC  can  be 
converted  for  use  on  a  new  computer  system  using  a  previous  assembly 
language  program  with  minimal  resource  expenditures. 

Each  program  has  been  stored  in  a  separate  tape  file.  The  first 
tape  file  contains  a  sequential  index  for  each  EDITSPEC  program  file. 

The  format  for  this  index  is  shown  below: 

FILE 
NO. 

3—10 

Right  • 

Justified 

For  conversion  of  the  data-handler  and  table-handler  programs 
see  Volumes  no.  Ill  and  IV. 


PROGRAM  SOURCE  DATE  LAST 

NAME  LANGUAGE  WRITTEN  DATE  MODIFIED 

13—20  23—40  43—50  53—60  Card  Columns 

Left  Left  DD/MM/YY  DD/MM/YY  Data  Form 

Justified  Justified 
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2  CHANGES  TO  THE  EOITSPEC  SYSTEM  PROGRAMS 


As  new  functions  are  incorporated  into  the  EDITSPEC  system,  the 
steps  below  should  be  rigorously  followed.  Executing  these  steps 
will  insure  that  the  changes  are  performed  correctly  and  are 
completely  documented.  See  the  programmers  manual  for  added  infor¬ 
mation. 

STEP  1:  -  Write  a  FORTRAN  program  well  documented  with  comment 
statements.  Follow  the  standard  documentation  procedures  below.  If 
an  existing  program  is  being  modified,  change  the  FORTRAN  program 
before  changing  the  assembly  programs.  Store  the  changed  FORTRAN 
program  in  correct  chronological  order.  The  following  information 
should  be  entered: 

Program  name:  Enter  the  name  as  in  the  first  line  of  the  function  or^ 
subroutine  with  arguments. 

Function:  Provide  a  brief  description  of  the  function  of  the  program. 

Author:  Give  the  author's  name  and  the  date  the  program  was  first  written 

Modifications:  List  the  author,  date  and  brief  statement  of  the 
reason  for  the  change(s). 

Language :  Indicate  the  programming  language  used. 

Calling  Sequence:  Describe  the  arguments  and  the  function  result. 

Routines  Called:  List  the  subroutines  and  functions  called  by  the 
program. 

Tasks  or  Modules:  Identify  the  tasks  or  modules  containing  this  routine. 

Variables:  Describe  all  variables  used  in  the  program. 

COMMON  variables  will  generally  be  described  in  a 
"main"  program,  referenced  in  this  section.  The 
structure  of  arrays  and  meaning  of  variables  should 
be  fully  described. 

Program  Logic:  Provide  a  detailed  description  of  both  the  algorithm(s) 
used  and  the  flow  of  the  program.  The  comment  statements 
that  provide  this  portion  of  the  documentation  will 
normally  be  scattered  throughout  the  program  in 
complete  English  sentences. 
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STEP  2:  Change  the  last  data  modified  on  the  EDITSPEC  system 
tape  file  index. 

STEP  3:  Change  the  FORTRAN  source  listing  on  the  documentation 
tapes. 

STEP  4:  Write  the  assembly  programs,  if  required. 

STEP  5:  If  required,  change  the  last  data  modified  on  the 
EDITSPEC  system  tape  file  index. 

STEP  6:  Change  the  assembler  listing  on  the  documentation 
tapes. 

STEP  7:  Change  the  system  integration  test  routines  to  com- 
pletely  test  the  new  feature. 

STEP  8:  Execute  the  entire  system  integration  test  routine 
package  and  replace  the  results  on  the  documentation  tapes. 

STEP  9 :  Revise  this  and  other  reports  if  required.  Document 
all  revisions  on  the  list  of  revisions  to  this  document  located  at 
the  beginning  of  the  reports. 

STEP  10:  Revise  all  calling  programs  as  required  by  the  change 
in  the  program  modified  by  repeating  steps  one  through  ten. 


C  3  CONTRACTING  FOR  COMPUTER.  SERVICES 


It  is  the  policy  of  the  Federal  government  to  periodically  rebid 
for  computer  services.  Preparation  for  the  rebidding  must  start  at 
least  12  months  before  the  current  computer  service  contract  expires. 


Activities  to  be  Performed 

The  milestones  and  activities  to  be  performed  in  converting  to  a 
new  computer  system  are  shown  in  Figure  1. 

The  first  step  is  to  review  the  previous  documentation  approved 
by  HQDA.  This^documentation  includes  the  Management  Information 
System  Economic  Analysis  (M1SEA),  Appendix  N,  and  the  scope  of  work 
for  the  current  contract.  Several  meetings  will  be  required  to  coor¬ 
dinate  the  activities  of  the  specifications,  systems-support ,  and 
procurement  sections.  A  new  set  of  documents  showing  the  anticipated 
work  load  for  the  next  contract  period  must  be  produced. 

The  second  activity  is  the  review  of  the  documentation  by  the 
Technical  Monitor  (TM),  HQDA  (DAEN-MCE-S) ,  and  the  Engineering  Di¬ 
vision  Management.  The  TM's  review  would  normally  take  one  week.  A 
coordination  meeting  and  rewriting  would  occupy  a  second  week.  Final 
review  and  approval  by  the  TM  would  take  place  during  the  third  week, 
and  the  approval  of  the  Engineering  Division  Management  would  be  ob¬ 
tained  during  the  fourth  week. 

The  documentation  would  then  be  sent  from  Engineering  Division 
to  OPRS  for  review  and  revision.  The  first  week  would  be  used  for 
review  and  the  second  for  a  review  conference.  The  rewriting  would 
be  performed  during  the  third  week,  after  which  OPRS  would  approve 
the  documentation  and  send  it  to  Engineer  Information  &  Data  Systems 
Office  (EIDSO). 

The  EIDSO  review  process  would  follow  the  same  pattern  as  the 
OPRS  review  process. 

The  DMIS  review  is  more  lengthy.  AR  18-1  requires  a  minimum  of 
60  days  for  review.  The  documents  are  reviewed  by  several  sections 
In  sequence.  The  Army  Audit  Agency  then  reviews  the  MISEA. 

It  Is  very  difficult  to  obtain  the  required  approval  to  award  a 
contract  within  60  d  s,  so  e*'  a  time  should  be  allowed  for  slip¬ 
page. 
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C  Once  final  approval  has  been  obtained,  the  bid  package  can  be 

finalized  and  sent  to  the  printer. 

A  preinvitation  letter  to  prospective  bidders  can  be  helpful  in 
reducing  the  number  of  prospective  bidders. 

The  bidders  should  be  given  a  minimum  of  90  days  to  prepare  and 
submit  their  bids,  as  bid  preparation  involves  a  great  deal  of  work. 
The  bidder  must  request  a  bid  package  and  wait  to  receive  it,  a  pro¬ 
cess  which  takes  about  two  weeks.  The  bidder  must  then  read  the  doc¬ 
umentation  provided,  consuming  another  two  weeks.  It  will  require 
about  four  weeks  for  bidder  to  convert  and  load  the  system  onto  his 
computer.  A  system's  integration  test  must  be  conducted  during  the 
following  week.  The  benchmark  test  will  take  another  two  weeks  to 
complete,  and  two  weeks  should  be  allowed  for  preparing  the  final 
bid. 

The  Government  should  allow  at  least  3  weeks  for  reviewing  the 
bids  and  awarding  a  contract.  The  Government  must  then  coordinate 
the  transfer  between  the  current  system  and  the  new  system,  after 
which  the  data  would  then  be  moved  to  .the  new  computer. 

Since  activities  rarely  go  according  to  schedule,  a  grace  period 
must  be  provided  before  the  current  computer  contract  expires.  At  a 
bare  minimum,  an  extra  month  should  be  allowed,  after  which  the 
^  EDITSPEC  system  would  be  completely  operational  on  the  new  computer. 

After  the  transfer  is  complete,  a  summary  report  should  be 
written  recording  the  problems  encountered  so  that  they  can  be  con¬ 
sidered  and  avoided  in  future  conversions.  This  report  should  be 
modified  as  required  to  reflect  better  approaches  to  the  activities. 


Previous  Contracts 

One  copy  of  each  contract  awarded  should  be  placed  in  Appendix  B 
of  this  volume,  which  will  serve  as  a  reference  appendix  for  the 
preparation  of  future  contracts. 
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4  PROGRAM  CONVERSION 


The  EDITSPEC  system  has  been  written  in  such  a  way  as  to  mini¬ 
mize  the  time  required  to  convert  from  one  computer  to  another.  All 
conversion  instructions  are  presented  as  comment  statements  within 
the  code  of  the  subroutines  given  in  Appendix  A.  A  standard  descrip¬ 
tion  of  the  conversion  process  for  each  subroutine  that  must  be  al¬ 
tered  is  given  in  the  appendix  which  should  be  reproduced  and  used  as 
a  guide  for  conversion. 

The  programmer  performing  the  conversion  should  carefully  follow 
the  instructions  given  in  the  comnents  and  in  Appendix  A. 

The  FORTRAN  programs  for  several  subroutines  have  been  rewritten 
in  assembly  language  to  improve  execution  speeds.  The  original  FOR¬ 
TRAN  programs  dan  be  used  for  the  initial  loading  of  the  EDITSPEC 
system.  As  new  assembly  language  routines  are  completed,  they  can 
then  replace  the  initial  FORTRAN  code.  Both  the  FORTRAN  and  IBM  BAL 
codes  are  included  on  the  documentation  tapes. 

The  folic  ing  programs  should  be  rewritten  in  assembly  language 
for  the  host  computer: 

UNLOK 

LOCK 

MC2ED 

RCNV2 

RCNVR 

MCMP 

CLOCK 

NCMP 

EX2UN 

TRANS 

ICOPY 

PACK 

UNPAK 


After  all  programs  have  been  written  in  assembly  language,  the 
new  programs  should  be  added  to  the  documentation  tapes  in  the 
location  immediately  after  the  last  assembler  or  FORTRAN  version  of 
the  basic  program.  Previous  programs  in  assembler  languages  should 
not  be  removed  from  the  documentation  tapes.  This  documentation  pro¬ 
cedure  will  make  it  possible  to  load  the  EDITSPEC  system  in  a  rela¬ 
tively  short  time  and  with  minimal  resource  onto  a  new  computer 
system  which  uses  an  assembler  that  has  been  used  at  some  previous 
time  in  the  history  of  EDITSPEC. 


5  OVERLAY  STRUCTURE 


The  complete  EDITSPEC  computer  code  occupies  over  2,500  bytes 
of  computer  storage.  The^system  can  be  overlayed  to  reduce  the  core 
requirements  to  under  800*  bytes.  The  overlay  structure  used  is 
shown  in  Figure  2. 


6  SYSTEM  INTEGRATION  TEST 


The  System  Integration  Test  (SIT)  is  a  test  of  the  completed 
computer  system  conducted  to  insure  that  the  system: 

1.  meets  system  objectives 

2.  is  fully  operational 

3.  is  ready  for  operational  testing 

4.  contains  no  unauthorized  features. 

The  input  for  the  SIT  is  contained  on  the  tapes  named 
CERLEDITSPEC.SIT.  SYSTEM. INDATA.  Each  command  in  the  EDITSPEC 
system  has  one  SIT  input  file  on  this  tape.  Each  file  corresponds  to 
one  complete  EDITSPEC  session.  All  input  tapes  are  unlabeled, 
written  at  a  density  of  800  bpi,  and  blocked  at  800  characters  per 
block. 

The  output  from  the  SIT  is  contained  on  the  tapes  named  CERL.ED- 
ITSPEC.SIT.SYSTEM.OUTDATA.  Each  command  in  the  EDITSPEC  system  has 
one  SIT  output  file  on  this  tape.  All  output  tapes  are  unlabeled, 
written  at  a  density  of  800  bpi,  and  blocked  at  1330  characters  per 
block.  Each  record  is  133  characters  long. 

Six  temporary  disk  files  are  required  for  program  execution, 
designated  as  follows: 

Name 

EEKl.editspec.aisystem 

CERL. EDITSPEC. BISYSTEM 
CERL. EDITSPEC. A1SIT 
CERL.EDITPSEC.B1SIT 
CERL. EDITSPEC. A1DCMNTS 
CERL. EDITSPEC. B1DCMNTS 

The  SIT  should  always  be  kept  up  to  date.  The  SIT  should  be 
conducted  to  insure  proper  conversion  of  computer  programs  before 
actual  benchmark  tests  are  conducted. 


7  BENCHMARK  PROCEDURES 


Introduction 


The  purpose  of  the  benchmark  tests  is  to  simulate  the  actual 
working  environment  so  that  actual  production  costs  can  be  estimated. 
The  benchmark  consists  of  four  parts,  each  of  which  is  described 
below.  The  instructions  to  the  bidder  for  running  the  benchmark  are 
given  in  the  contract  in  Appendix  B. 


Initial  System  Loading 

This  part  of  the  test  will  fully  load  the  EDITSPEC  system  tables 
with  data  on  users,  supervisors,  documents,  accounts,  and  formats  as 
they  would  be  expected  to  exist  during  normal  system  operation.  All 
document  data  sets  must  be  referenced  by  one  .new.  command  during 
this  loading. 


Test  One 


The  first  test  loads  and  edits  ten  25-page  documents  similar  to 
an  average  OCE  guide  specification.  Documents  are  named  10CECE220.01 
through  10CECE200.10.  The  normal  editing  and  printing  commands  are 
included  with  each  document.  This  test  is  conducted  by  one  EDITSPEC 
user  under  the  bidder's  normal  computer  system  operating  conditions. 


Test  Two 


The  second  test  loads  and  edits  55  documents,  each  25  pages 
long,  similar  to  a  typical  OCE  guide  specification.  The  documents 
are  named  10CECE220.il  through  10CE220.65.  The  normal  editing  and 
print  commands  are  included  with  each  document.  The  test  is  conduc¬ 
ted  by  55  EDITSPEC  users  simultaneously  under  the  bidders  normal  com¬ 
puter  system  operating  conditions. 


Comparison  of  Tests  One  and  Two 

Comparison  of  both  time  and  charges  for  the  processing  of  one 
document  from  test  one  and  one  document  from  test  two  will  indicate 
the  efficiency  of  the  system  when  unloaded  and  when  fully  loaded  with 
EDITSPEC  users. 


Test  Three 


This  test  simulates  the  total  size  of  a  typical  project.  One 
project  named  PR01CE220.  02  is  executed.  This  document  consists  of 
five  pages  copied  from  a  guide  specification  and  one  page  entered  by 
the  input  command.  The  text  is  copied,  entered,  tested,  and  printed 
in  the  first  edit  cycle.  Four  edit  cycles  are  performed  using  global 
replacement  commands  to  simulate  normal  editing.  A  second  printing 
of  the  entire  project  should  be  performed  at  the  close  of  the  fourth 
edit  cycle.  The  results  of  this  output  should  be  multiplied  by  50  to 
simulate  the  average  300-page  specification. 


Benchmark  Test  Performance 


This  benchmark  test  should  be  conducted  every  three  months  to 
verify  that  the  performance  of  the  contractor's  system  has  not 
degraded  nor  have  the  charges  changed. 
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8  DATA  CONVERSION 


Once  the  service  contract  has  been  awarded,  the  existing  data 
must  be  converted  to  the  new  computer.  The  system  data  conversion 
process  is  shown  in  Figure  3.  The  conversion  command  is  given  in  Ap¬ 
pendix  C. 


FIGURE  I 

COMPUTER  SERVICES 
CONTRACTING  ACTIVITY 
PLANNING  SCHEDULE 
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TM 

REVIEW 


DOCUMENTS  TO  OPRS 


OPRS 
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DOCUMENTS  TO  EIDSO 
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REVIEW 
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DOCUMENTS  TO  DMIS 

% 
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FINAL  BID  PACKAGE  COMPLETE 

PREADVERT ISMENT  LETTER 

ADVERTIZE  IN  CBD 

BID  OPENMG 

CONTRACT  AWARD 

SIT  B  BM  COMPLETED 

FULLY  OPERATIONAL  NEW 
COMPUTER  SYSTEM 


DESCRIPTION 


3  DATA  CONVERSION 


CONVERSION  MANUAL 


SUBROUTINE :  CLOCK _ 

A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  Entire  routine  must  be  rewritten 
in  assembler  language  of  new  host  computer  system. _ 


B.  SUBROUTINE  CONVERSION  COMPLETED  BY 


Mb 


CONVERSION  MANUAL 


SUBROUTINE:  CWWTR 


£<tf‘  Ct  4^  4J 


.  CONVERSION  ITEM:  IRES  (  )»  DUMMY 


NCRES 


1.  Locations  in  Text: _ ISN  24,  47,  48 


2.  Machine  Dependence:  Site  of  Array 


3.  Conversion  Procedures:  Determine  the  size  of  the _ 

IRES  Array  by  adding  four  to  the  number  of  resources  reported 
In  the  moni  routine  which  is  NCRES  in  this  routine.  Change  the 
dumny  variable  whenever  used  to  the  correct  machine  dependent  array. 


4.'  Conversion  Completed  and  Tested  by: 
Date: _ 


CONVERSION  MANUAL 


SUBROUTINE :  CMLIST 


(j 


.  CONVERSION  ITEM:  IRESN,  I AUG,  I SUM 


1.  Locations  in  Text: 


2.  Machine  Dependence:  IRESN  is  the  total  number  of 

entries  written  to  tape/disk. _ 


3.  Conversion  Procedures:  Get  IRESN  equal  to  the  total 
number  of  words  written  to  the  disk  by  CMMNTR.  IAUG  &  ISUM 
must  be  dimensioned  according  to  IRESN. 


4.  Conversion  Completed  and  Tested  by: 
Oaten _ 


•  CONVERSION  MANUAL 


SUBROUTINE: 


A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  Entire  routine  must  be  rewritten 
in  assembler  language  of  new  host  computer  system  (FORTRAN  version 
of  this  routine  is  available  for  reference  and/or  provisional  use.) 


B.  SUBROUTINE  CONVERSION  COMPLETED  BY: 


DATE: 


< 

\ 


CONVERSION  MANUAL 


SUBROUTI NE :  CONV1 _ 

A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  Entire  routine  must  be  rewritten 
in  assembler  language  of  new  host  computer  system  (FORTRAN  version 
of  this  routine  is  available-. for  reference  and/or  provisional  use.) 


B.  SUBROUTINE  CONVERSION  COMPLETED  BY 


CONVERSION  MANUAL 


( 

\ 

SUBROUTINE:  ENTER _ ’ _ 

A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  New  format  statement. _ 


r 


CONVERSION  MANUAL 


SUBROUTINE:  INPUT 


A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  Format  statement. 


B.  SUBROUTINE  CONVERSION  COMPLETED  BY: 


c 

CONVERSION  MANUAL 

SUBROUTINE :  L0CK _ 

A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  Entl>e  routine  must  be  rewritten- 
in  assembler  language  of  new  host  computer  system. 


B.  SUBROUTINE  CONVERSION  COMPLETED  BY 


CONVERSION  MANUAL 


r 


SUBROUTINE :  LSTBL _ 

A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  Format  statements 


All  programs  called  from  this  routine  must  be  changed. 


B.  SUBROUTINE  CONVERSION  COMPLETED  BY: 


CONVERSION  MANUAL 


SUBROUTINE  MfMP _ 

A.  NEW  SYSTEM  PARAMETERS  REQUIRED;  Entire  routine  must  bp  rpwrit.tgn 
in  assembler  language  of ’new  host  computer  system. _ 


B.  SUBROUTINE  CONVERSION  COMPLETED  BY; 
_  DATE; 


r 


V 


CONVERSION  MANUAL 


SUBROUTINE  »CMP _ 

A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  Entire  routine  must  be  rewritten 
In  assembl  r  language  of  new  host  computer  system. 


CONVERSION  MANUAL 


r 


CONVERSION  MANUAL 


SUBROUTINE j  PfcTOC _ 

A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  "b'jAJA/yiJr C _ 

ALL  oc/\~rtc  /i'  / D £~ AS 4  t?q  MS  o  _ 

~THE  Data  j?T  f~of^  TH/=  USFP-J 

•  £ocA£  /7<rz>  £>A&  t>  ~-r&/?/i///o/i-<L  n~j 

AiA-c/t  /aje  t>  e  vfTArr . _ 


c 


B.  SUBROUTINE  CONVERSION  COMPLETED  BY: 
_  DATE: 


of/ 


& 


e 


* 

r 


CONVERSION  MANUAL 


SUBROUTINE:  PRB0DY 


A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  ponnat  statements  need  conversion. 


B.  SUBROUTINE  CONVERSION  COMPLETED  BY: 
_  DATE: 


J(r 


i 


CONVERSION  MANUAL 


SUBROUTINE : _ RCNVR _ 

A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  Entire  routine  must  be  rewritten 
in  assembler  language  of- new  host  computer  system.  (FORTRAN 
version  of  this  routine  is  available  for  reference  and/or  provisional 
use.) 


B.  SUBROUTINE  CONVERSION  COMPLETED  BY 


c 


CONVERSION  MANUAL 


SUBROUTINE : _ RCNV2 _ 

A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  Entire  routine  must  be  rewritten 
in  assembler  language  of ‘new  host  computer  system.  _ 


B.  SUBROUTINE  CONVERSION  COMPLETED  BY: 


CONVERSION  MANUAL 


SUBROUTI NE :  TRANS _ 

A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  Entire  rputine  must  be  rewritten 
in  assembler  language  of • new  host  computer  system: 


B.  SUBROUTINE  CONVERSION  COMPLETED  BY: 


CONVERSION  MANUAL 


Lw 

c 

SUBROUTINE  UNLOK 

A.  NEW  SYSTEM  PARAMETERS  REQUIRED:  Entire  routine  must  be  rewritten  ' 
in  assembler  language  of- new  host  computer  system. _ 


?  — . . . -  - 

B.  SUBROUTINE  CONVERSION  COMPLETED  BY: 
_ ' _  DATE: 


APPENOIX  B 

PAST  CONTRACTS 
(To  be  added  later) 


DATA  SET  CONVERSION 
DSCN 


PURPOSE 


This  system  command  allows  the  user  to  create  a  machine- independent  con¬ 
version  tape  (on  a  user-specified  device)  from  an  existing  document 
dataset  or  the  system  dataset.  This  tape  is  used  to  transfer  EDITSPEC 
data  from  one  computer  system  to  another. 


GENERAL  FORM 


j  .DSCNjdataset  name;  unit  number;  control  option. 


where  dataset  name  is  a  one  to  six  character  n?me 

of  the  dataset  to  be  dumped  to 
tape 

unit  number  is  the  logical  unit  number 

of  the  tape  drive  where 
the  conversion  output 
Is  to  be  written 

control  option  Is  a  number  between  0  and 

3  that  specifies  the  process¬ 
ing  option  for  this 
conversion  run 


FIELD  OPTIONS 


FIELD  OPTIONS  DEFAULT 


name  of  an  existing  SYSTEM  dataset, 
dataset,  or  empty 
field  to  Indicate 
system  dataset. 


1.  dataset  none 


2.  unit  number 


any  FORTRAN  logical  unit  10 

unit  number  assigned 

to  an  output  device 

(valid  range  is  1  to 

99). 


3.  control  option  a  number  between  0  option  0  -  normal 

and  3t  to  indicate  processing 
processing  mode 
(only  affects  docu¬ 
ment  dataset  con¬ 
versions,  ignored 
on  system  dataset 
conversion): 

0-normal  processing 

1- speclal  select 
processing 
(see  below) 

2- reset  all  docu¬ 
ments  on  speci¬ 
fied  dataset  to 
status  'available' 
from  status  'con¬ 
verted  and  un¬ 
available' 

3- rebuild  ISDDT 
table  for  all 
documents  7n” 

EDITSPEC  system 


SPECIAL  NOTES 

1.  This  command,  because  of  the  extensive  processing  Involved,  should 
be  Issued  only  from  batch  mode. 

2.  Only  the  'supreme  supervisor*  Is  permitted  to  Issue  this  command. 
The  'supreme  supervisor'  Is  defined  as  the  first  user  who  logged 
Into  this  EDITSPEC  system  at  system  Initialization. 


DATA  SET  CONVERSION 
DSCN 


3.  The  'special  select'  processing  option  requires  the  preparation  of 
additional  'directive  records'  to  control  the  selection  of  documents 
for  conversion.  Since  these  directives  are  in  a  fixed  format  and 
not  prompted  for,  use  of  this  option  is  restricted  to  batch  mode 
operation.  The  general  format  of  a  directive  record  is: 


Character  Position 

Information 

1-2 

must  be  blank 

3 

directive  type 

4 

must  be  blank 

5-16 

document  name,  left 
justified,  padded  on 
right  with  "8"  characters 

17 

must  be  blank 

18-23 

new  dataset  name,  left 
justified,  padded  on 
right  with  "@"  characters 

24-80 

must  be  blank 

Below  is  a  brief  description  of  the  different  directive  types: 

Type  1:  Move  a  specific  document  to  the  conversion  tape. 

The  document  is  located  on  the  dataset  specified 
by  the  "dataset  name"  field  on  the  DSCN  command, 
and  is  transferred  in  such  a  fashion  that  It  will  be 
restored  to  the  dataset  Indicated  by  "new  dataset 
name"  on  the  target  system  receiving  the  conversion 
tape.  After  the  document  is  copied  to  the  con¬ 
version  tape,  the  ISDDT  table  is  marked  in  such 
a  fashion  to  prohibit  further  editing  or  accessing 
to  this  document. 

Type  2:  Mark  a  specific  document  as  "converted"  without 
•  actually  moving  the  document. 

Type  3:  Remove  the  "converted"  mark  from  a  specific  document, 
thus  allowing  access  to  the  document  again. 

Type  4:  Move  all  unmarked  documents  on  the  dataset  specified 
on  the  DSCN  command  to  tape,  transferring  them  in 
such  a  way  that  they  will  be  restored  to  dataset 
"new  dataset  name"  on  the  target  system.  The  docu¬ 
ment  name  field  of  this  directive  Is  Ignored.  All 
documents  that  are  successfully  copied  to  tape  will 
be  marked  as  "converted"  (this  directive  is  the 
equivalent  of  specifying  control  option  0  on  the 
DSCN  coomand). 

Type  5:  End  of  directives  flag. 


DATA  SET  CONVERSION 
DSCN 


As  many  directives  as  desired  may  follow  the  DSCN  command,  but  there 
must  be  one  and  only  one  type  5  directive  as  the  last  directive  issued. 
The  directives  are  read  from  the  principle  input  unit  for  the  EDITSPEC 
system,  and  thus  may  not  be  located  in  text  files  that  are  executed  in¬ 
directly  by  the  EXEC  command. 

4.  More  detailed  information  about  inter-system  conversion  procedures 
and  internals  can  be  found  in  the  EDITSPEC  SYSTEMS  MANUAL  VOLUME  V: 
Conversion  and  Extension. 


EXECUTION  PROCEDURE 

% 

The  dataset  name  is  checked  to  make  sure  It  specifies  a  valid  dataset. 
The  control  option  is  decoded  and,  if  necessary,  additional  selection 
directives  are  read  from  the  command  stream.  Any  tables  to  be  copied 
(system  or  document)  are  formatted  and  written  to  the  conversion  tape 
(on  the  unit  specified)  as  a  sequence  of  special  EDITSPEC  conmands  to  be 
executed  on  the  target  EDITSPEC  system. 


COMMAND  VARIATIONS 


Var.  #1.  .DSCN. 


Example  #1. 

Command:  .DSCN. 

Action  performed:  A  series  of  special  EDITSPEC  commands 

are  written  to  unit  10.  These 
comnands,  when  executed  on  a  new 
EDITSPEC  system,  will  duplicate 
all  system  table  information  on 
the  target  system. 

System  and  document  datasets  after:  no  change 

Example  #2. 

System  datasets  before:  System  dataset  Is  named  'SYSTEM' 

Command:  .0SCN_SYSTEM;31. 

Action  performed:  The  system  tables  are  copied  to  tape 

as  before,  writing  to  logical  unit 
number  31. 

System  and  document  datasets  after:  no  change 


nATA  SET  CONVERSION 
OSCN 


Var.  #2.  .OSCN  document  dataset  name. 


Example  #1. 

Document  datasets  before: 

DIRECTORY  OF  DOCUMENTS  ON  DATASET  "DSl" 
DOC  NAME  STATUS 

DOCUMENTA  OK 

DOCUMENTB  OK 

DOCUMENTC  CONV 

DOCUMENTD  OK 


Command:  .DSCN_DS1. 

Action  performed:  All  non-converted  documents  on  dataset 

DS1  are  individually  formatted  and  written 
to  unit  10.  After  each  document  is  copied. 
Its  status  is  changed  from  'OK'  to  'CONV', 
restricting  Its  access  to  prevent 
modification  (note  that  in  this  example 
'DOCUMENTC*  is  not  processed). 

Document  datasets  after: 


DIRECTORY  OF  DOCUMENTS  ON  DATASET  "DSl" 


DOC  NAME 

STATUS 

DOCUMENTA 

CONV 

DOCUMENTB 

CONV 

DOCUMENTC 

CONV 

DOCUMENTD 

CONV 

Example  #2. 

Document  datasets  before:  same  as  example  #1 

Command:  .DSCN_DS1;25;0. 

Action-  performed:  Documents  DOCWCNTA,  DOCUMENTB, 

and  DOCUMENTD  are  copied  to  unit  25. 
(Note  that  option  0  is  explicitly 
stated,  rather  than  implicitly 
by  default.) 

Document  datasets  after:  same  as  example  #1 


DATA  SET  CONVERSION 
DSCN 


Var.  #3.  .DSCN_document  dataset  name;;l. 
Example  #1« 


C 


Document  datasets  before: 


DIRECTORY 

OF  DOCUMENTS  ON  DATASET 

DOC  NAME 

STATUS 

DOCUMENTA 

OK 

DOCUMENTB 

OK 

DOCUMENTC 

CONV 

DOCUMENTD 

OK 

DOCUMENTE 

CONV 

II 


Commands:  .DSCN  DS1;;1. 

bb 1 bDOCUME  NT A@@@bOF 1 @@@  (a) 

bblbD0CUMENTB@@@bDS2@@@  (b) 

*  bb2bD0CUME NTD@@@b@@@@@@  (c) 

bb5  (d) 

Action  performed:  Processing  option  1  is  requested.  Therefore 

a  series  of  directives  must  follow  the  DSCN 
command,  which  itself  must  be  issued  from  batch 
mode.  The  first  directive  (a)  requests  that 
'DOCUMENTA'  on  dataset  'DSl'  be  copied  to  unit 
10,  and  then  marked  as  converted.  The  copy  is 
performed  in  such  a  manner  that  'DOCUMENTA'  will 
be  restored  to  dataset  'DSl'  on  the  target  EDITSPEC 
system.  The  second  directive  (b)  requests  the  same 
operation  be  performed  against  'DOCUMENTB',  except 
that  the  copy  will  be  done  so  .that  'DOCUMENTS'  will 
be  restored  to  dataset  'DS2'  on  the  target  system. 
Directive  (c)  requests  that  'DOCUMENTD'  be  changed 
from  status  'OK'  to  status  'CONV',  without  actually 
copying  the  document  to  tape,  thus  making  'DOCUMENTD 
Inaccessible  for  editing.  Directive  (d)  indicates 
that  It  Is  the  last  of  the  DSCN  directives,  and 
that  the  system  should  expect  an  EDITSPEC  command 
as  its  next  line  of  input. 


Document  datasets  after : 


DIRECTORY  OF  DOCUMENTS  ON  DATASET  "DSl' 


DOC  NAME 
DOCUMENTA 
DOCUMENTB 
DOCUMENTC 
DOCUMENTD 
DOCUMENTE 

IS 


STATUS 

CONV 

CONV 

CONV 

CONV 

CONV 
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( 


Example  f 2 . 

Document  datasets  before:  Same  as  example  #1 


Commands:  .DSCN  DS1;;1. 

bb4bbBhbbbbbbbbbbDS3@@(?  (e) 
bb3bD0CUME  NTB@@@b@@@@@(?  (f) 
bb3bD0CUMENTC@@@b@@@@@@  (g) 
bb5b  (h) 


Action  performed:  As  in  example  #1,  directive  input  is 

required.  Directive  (e)  requests  that  all 
.  non-converted  documents  on  ' DS1 *  be  copied 

to  unit  10,  in  such  a  way  that  they  will 
be  restored  to  dataset  'DS3'.  Each  docu¬ 
ment  is  marked  as  'CONVerted1  when  it  is 
copied.  Directives  (f)  and  (g)  request 
that  'DOCUMENTB'  and  'DOCUMENTC'  be 
changed  from  status  'CONV1  to  status  'OK* 
in  order  to  make  them  accessible  for  further 
editing.  Directive  (h)  terminates  con¬ 
version  processing  and  returns  to  normal 
EDITSPEC  processing. 


Document  datasets  after: 


DIRECTORY  OF  DOCUMENTS  ON  DATASET  "DS1" 


DOC  NAME 

STATUS 

DOCUMENTA 

CONV 

DOCUMENTB 

OK 

DOCUMENTC 

OK 

DOCUMENTD 

CONV 

DOCUMENTE 

CONV 

Var.  #4.  .DSCNdocument  dataset  name;;2. 


Example  #1. 

Document  datasets  before: 

DIRECTORY  OF  DOCUMENTS  ON  DATASET  "DS1" 
-  DOC  NAME  STATUS 

DOCUMENTA  CONV 

DOCUMENTB  OK 

DOCUMENTC  CONV 

Command:  .DSCN  DS1;;2. 

¥1 


DATA  SET  CONVERSION 
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Action  performed:  All  documents  on  dataset  DSl  will  be 

changed  from  status  'CONV'  to  status 
'OK'.  This  permits  subsequent  editing 
and  accessing  of  converted  documents. 


Document  datasets  after: 

DIRECTOR  OF 
DOC  NAME 
DOCUMENTA 
DOCUMENTB 
DOCUMENTC 


DOCUMENTS  ON  DATASET  "DSl" 
STATUS 
OK 
OK 
OK 


Var.  #5.  .DSCN  ;;3. 


Example  #1. 

Document  and  system  datasets  before:  ISDDT  table  incorrect  or 

corrupt,  documents,  'DOCUMENTA* 
and  'DOCUMENTB'  are  on  dataset 
'DSl',  document  'DOCUMENTX'  is 
on  dataset  ' DS2 ' . 

Command:  .DSCN_;;3. 

Action  performed:  The  ISDDT  table  is  deleted  and  entirely 

re-created,  using  information  from  the  ISDIR 
table.  All  documents  indexed  by  the  ISDIR 
table  are  cataloged,  regardless  of  which 
dataset  they  are  stored  on. 

Document  and  system  datasets  after: 

DIRECTORY  OF  DOCUMENTS  ON  DATASET  "DSl" 

DOC  NAME  STATUS 

DOCUMENTA  OK 

DOCUMENTB  OK 

DIRECTORY  OF  DOCUMENTS  ON  DATASET  "DS2" 

DOC  NAME  STATUS 

DOCUMENTX  OK 


MESSAGES  -  All  messages  self-explanatory. 
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